Platform: OpenFeint Android SDK 1.6

Readme.html for OpenFeint Android SDK 1.6
Release date 12.15.2010
Release Notes Copyright (c) 2009-2010 Aurora Feint Inc.
All Rights Reserved.

OpenFeint Android Quick Start Guide


<<Prev  Next >>
 

Add OpenFeint features

Once you have integrated and initialized your application with OpenFeint, you can add OpenFeint features.

Achievements

An OpenFeint achievement is an event in a game for which a player is granted a block of points. Each game can award a total of 1000 achievement points per player. The maximum number of points that a player can earn per achievement is 200. An achievement can be hidden, in which case the player does not know about the achievement until the achievement points have been earned.

Leaderboards
A leaderboard is a list of players who have gotten the highest scores for a particular accomplishment in a game. You can give players points and take points away from a specified leaderboard.

In the steps that follow, we show how to add the ability to unlock an achievement and post a score to a leaderboard to an OpenFeint-enabled game.

NOTE: The following instructions walk through a subset of the capabilities already implemented in the sample app. For insight, trace and experiment with the implementation in the sample application.

  1. Sign into †he OpenFeint dev dashboard using the developer account and game description you created earlier.
  2. Define a new achievement:
    • Select Achievements under the Features tab.
    • Click the + Add Achievement button.
    • Provide a Title for the achievement such as Caught the Brass Ring.
    • Provide a numeric Feint Score. The Feint Score is the number of achievement points the player will receive when the achievement is attained. For purposes of this tutorial, set the Feint Score to a value of 10.
    • Provide a description such as Just a test achievement.
    • Ignore all other fields for now.
    • Scroll to the bottom of the page and click the Save Achievement button.
    • A text box confirms that you have successfully created the achievement.
  3. Define a leaderboard.
    • Select Leaderboards under the Features tab.
    • Click the + Add Leaderboard button. The Create New Leaderboard page appears.
    • Provide a name for the leaderboard such as Experimental Scores.
    • The Descending Sort Order checkbox should be checked by default.  Keep it checked.
    • Check the Allow Worse Scores checkbox.
    • Ignore all other fields for now.
    • Scroll to the bottom of the page and click the Save Leaderboard button.
    • A text box confirms that you have successfully created the leaderboard.
  4. Use the sample app to see the achievement and leaderboard you just created.
    • If you build a copy of the sample app using the same product key as your own application, you will be able to use the sample application to view and edit the same scores, achievements, etc. that are stored server side for your application.
    • This allows you to use the sample app to help test how your own app is managing this data.
  5. Add code to unlock an achievement:
    • Edit the source file in which you will unlock the achievement:
      1. Add the following imports:
        import com.openfeint.api.resource.Achievement;
        import android.widget.Toast; // Used for presenting diagnostic messages.
      2. Add the following code at the point in the code where a player action will cause an achievement to be unlocked:
        new Achievement("achievementID").unlock(new Achievement.UnlockCB () {
        		@Override public void onSuccess() {
        			MyClass.this.setResult(Activity.RESULT_OK);
        			MyClass.this.finish();
        		}
        
        		@Override public void onFailure(String exceptionMessage) {
        			Toast.makeText( MyClass.this,
        				"Error (" + exceptionMessage + ") unlocking achievement.",
        				Toast.LENGTH_SHORT).show();
        
        			MyClass.this.setResult(Activity.RESULT_CANCELED);
        			MyClass.this.finish();
        		}
        });
        Notes:
        • Be sure to replace the string achievementID above with the number of an achievement you created in your application.
        • Also replace MyClass with the name of the class containing this code.

        The following code unlocks the achievement specified by the achievement ID "531293":

        new Achievement("531293").unlock(new Achievement.UnlockCB () {
        		@Override public void onSuccess() {
        			MyClass.this.setResult(Activity.RESULT_OK);
        			MyClass.this.finish();
        		}
        
        		@Override public void onFailure(String exceptionMessage) {
        			Toast.makeText( MyClass.this,
        				"Error (" + exceptionMessage + ") unlocking achievement.",
        				Toast.LENGTH_SHORT).show();
        
        			MyClass.this.setResult(Activity.RESULT_CANCELED);
        			MyClass.this.finish();
        		}
        });
      • Use the sample application as described above, to verify that the achievement unlock succeeded.
  6. Add code to post a score to a leaderboard:
    • Edit the source file in which you will unlock the achievement: Add the following imports:
      import com.openfeint.api.resource.Leaderboard;
      import com.openfeint.api.resource.Score;
      import android.widget.Toast; // Used for presenting diagnostic messages.
      
    • Add the following code at the point in the code where a score is to be saved to the OpenFeint database:
      long scoreValue = longScoreValue;
      Score s = new Score(scoreValue, null); // Second parameter is null to indicate that custom display text is not used.
      Leaderboard l = new Leaderboard("leaderboardID");
      s.submitTo(l, new Score.SubmitToCB() {
      	@Override public void onSuccess(boolean newHighScore) {
      		// sweet, score was posted
      		MyClass.this.setResult(Activity.RESULT_OK);
      		MyClass.this.finish();
      	}
      
      	@Override public void onFailure(String exceptionMessage) {
      		Toast.makeText(MyClass.this,
      		"Error (" + exceptionMessage + ") posting score.",
      		Toast.LENGTH_SHORT).show();
      		MyClass.this.setResult(Activity.RESULT_CANCELED);
      		MyClass.this.finish();
      	}
      });
      
      Notes:
      • Replace the longScoreValue with the number of points the user has received in total in this game.
      • Replace the string leaderboardID above with the number of a leaderboard you created in your application.
      • Also replace MyClass with the name of the class containing this code.

      The following code will submit a score value of 10 for the current user to the leaderboard ID "531293". Please replace this value with an actual leaderboard ID associated with your product key. Please replace "MyClass" with the name of the class containing this code.

      long scoreValue = 10;
      
      Score s = new Score(scoreValue, null); // Second parameter is null to indicate that custom display text is not used.
      	Leaderboard l = new Leaderboard("531293");	
      	s.submitTo(l, new Score.SubmitToCB() {
      		@Override public void onSuccess(boolean newHighScore) {
      			// sweet, score posted
      			MyClass.this.setResult(Activity.RESULT_OK);
      			MyClass.this.finish();
      		}
      
      		@Override public void onFailure(String exceptionMessage) {
      			Toast.makeText(MyClass.this,
      			"Error (" + exceptionMessage + ") posting score.",
      			Toast.LENGTH_SHORT).show();
      			MyClass.this.setResult(Activity.RESULT_CANCELED);
      			MyClass.this.finish();
      		}
      	});
      
      • Use the sample app, as described above, to verify that the score posted successfully.

    You can also use the dev dashboard to view the top few scores posted to a leaderboard and remove scores posted for testing purposes. Note that this technique is not practical for dealing with scores on an active leaderboard containing thousands of entries.